FormDialogBuilder

使用 API 自定义渲染一个表单，并以对话框的形式打开。

FormDialogBuilder

FormDialogBuilder 是通过代码创建表单对话框的 API 对象，你可以通过 FormDialogBuilder 来组织表单项和布局，并且像开发一个表单一样，基于表单的相关事件编写个性化的逻辑。

类型	名称	参数类型	返回类型	说明
方法	addFieldSet(options)	AddFieldSetOptions	FieldSet	在表单默认布局中添加一个字段集合， 一个字段集合会渲染成一个带有标题的区域。
方法	addSubGrid(options)	AddSubGridOptions	SubGrid	在表单默认布局中添加一个明细表。
方法	addTabs()	void	Tabs	添加一个页签布局容器， 可以在页签布局下添加子页签。
方法	open(options)	OpenOptions	void	初始化表单对话框

addFieldSet(options) 添加字段集合

addFieldSet 用于添加一个基于流式布局实现的字段集合组件。组件由两部分组成：标题区 和 字段内容区。

标题区会在左侧显示标题文字。

字段内容区中，字段按照从左到右、从上到下的顺序依次排列。通过 fieldsPerLine 属性可以设置每一行显示的字段个数。

单据中常见的表头字段的区块就是 FieldSet。

options 参数

名称	类型	说明	必填	默认值
title	string	字段标题		""
fieldsPerLine	number	每行显示字段个数		4

返回值

FieldSet 字段集合

语法

// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();

// 添加一个标题为 “基本信息” 的区域
const baseFieldSet = formDialogBuilder.addFieldSet({
  title: '基本信息',
  fieldsPerLine: 2
});

// 添加一个标题为“名称”的文本类型字段
baseFieldSet.addField({
  id: "name",
  title: "名称",
  type: 'Text'
});

注意

如果不设置 title 属性或设置为空字符串 ""，那么对应渲染的字段集合区域就不会显示标题区域。

addSubGrid(options) 添加明细表

addSubGrid 用于添加一个以表格展示的明细表组件。组件由两部分构成：标题区 和 表格区。

标题区会在左侧显示标题文字。

表格区中，表头按照字段顺序从左到右依次构建。明细表中的每一行数据会作为表格中的一行记录进行展示。

单据中常见的明细表就是 SubGrid。

options 参数

名称	类型	说明	必填	默认值
id	string	明细表字段名	☑️	-
title	string	明细表标题		""

返回值

SubGrid 明细表

语法

// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();

// 添加一个标题为“人员明细”的明细表区域
const userGrid = formDialogBuilder.addSubGrid({
  fieldName: 'users',
  title: "人员明细"
});

// 在明细表中，添加一个标题为“人员”的外键字段，外键指向 User 表，并设置列宽为 200.
const user = userGrid.addField({
  id: "user",
  title: "人员",
  type: "EntityRef",
  source: 'User',
  width: 200
});

// 在明细表中，添加一个标题为“天数”的数字字段，该字段会显示在“人员”右侧。
userGrid.addField({
  id: "days",
  title: "天数",
  type: "Number"
});

注意

如果不设置 title 属性或设置为空字符串 ""，那么对应渲染的字段集合区域就不会显示标题区域。

addTabs(options) 添加页签容器

addTabs 用于添加一个页签模式的容器组件。如果我们创建的表单中，信息可以以某种明确的维度进行分组。那么我们可以使用页签布局来显示的表达这个分组，提高用户的体验。

单纯添加页签容器是无法工作的，页签容器（Tabs）需要页签（Tab）一起配合，才能完成一个完整的页签定义。

返回值

Tabs 页签容器

语法

// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();

// 添加一个页签分组
const tabs = formDialogBuilder.addTabs();

// 在页签分组下添加一个标题为“销售属性”的页签
const salesTab = tabs.addFieldSetTab({
  title: "销售属性"
});

// 在“销售属性”页签中，添加“售价”字段
salesTab.addField({
  id: "price",
  title: "售价",
  type: "Amount"
});

// 在 “销售属性” 右侧，添加一个标题为“库存属性”的页签，这个页签里显示一个明细表
const inventoryGrid = tabs.addSubGridTab({
  title: "库存属性"
  fieldName: "inventories"
});

注意

1. 如果页签容器下没有通过 addTab 或 addSubGridTab 来添加页签，那么最终这个页签容器不会进行渲染。
2. 和 FieldSet 不同，页签的 title 属性必填。

open(options) 初始化表单对话框

在完成表单数据和布局定义后，可以通过 open 打开表单对话框。这会同步创建一个全新的表单实例，该表单拥有独立的运行空间、独立的生命周期及相关表单上下文。如果要在这个表单上使用 Client API，则需要通过 options 来传递相关的表单事件监听处理函数。

options 参数

名称	类型	说明
title	String	对话框标题
size	String	对话框大小，可选值：small、middle、large、largest， 默认值：largest
value	Object	表单初始值
formOnLoad	Function	表单初始化后触发，详细介绍
fieldOnChanged	Function	表单中任一字段值发生改变时被触发，详细介绍
subGridOnChanged	Function	明细表数据发生变化时，对明细表的 添加、复制、删除 会触发，详细介绍
subGridRowOnCreated	Function	在明细行创建之后触发，详细介绍
subGridRowOnInit	Function	在明细行初始化之后触发，详细介绍
dialogOnCancel	Function	在用户点击 对话框右上角 或 底部取消按钮 时触发，详细介绍
dialogOnConfirm	Function	在用户点击 底部确认按钮 时触发，详细介绍

FieldSet 字段集合

FieldSet 是一个基于流式布局实现的字段集合，集合中的字段按照从左到右、从上到下的顺序依次排列。你可以通过 addField 给相应集合中添加字段。

类型	名称	参数类型	返回类型/类型	说明
方法	addField(options)	AddFieldOptions	Field	在字段集合中添加一个字段

addField(options) 添加字段

在字段集合 FieldSet 中添加一个字段。添加的多个字段会按照 addField 的调用顺序决定 FieldSet 中的展示顺序。

options 参数

名称	类型	说明	必填	默认值
id	string	字段名称	☑️	-
title	string	字段标题	☑️	-
type	FieldType	字段类型	☑️	-
decimal	number	当 type = "Number" 时， 通过 decimal 指定小数位精度	-	2
source	string	当 type = "EntityRef" 或 "EnumRef" 时， 通过 source 指定引用对象。		-

语法

// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();

// 添加一个标题为 “基本信息” 的区域
const baseFieldSet = formDialogBuilder.addFieldSet({
  title: '基本信息',
  fieldsPerLine: 2
});

// 添加一个标题为“名称”的文本类型字段
baseFieldSet.addField({
  id: "name",
  title: "名称",
  type: 'Text'
});

// 添加一个标题为“业务日期”的日期类型字段
baseFieldSet.addField({
  id: "businessDate",
  title: "业务日期",
  type: "Date"
});

// 添加一个标题为“业务员”的外键类型字段，外键指向人员
const userField = baseFieldSet.addField({
  id: "businessDate",
  title: "业务员",
  type: "EntityRef",
  source: "User"
});

Field 字段

Field 是单个字段的API对象。你可以通过 Field 给字段设置相关选项及参数。

类型	名称	返回类型/类型	说明
属性	id	string(read-only)	字段名，在调用 addField 时指定。在获取表单数据时， 该字段的值会以 id 作为父对象（表单或明细表行）的 key。
属性	type	string(read-only)	字段类型，在调用 addField 时指定。 不同字段类型的交互组件不同。具体可以参考 FieldType 类型集合

FieldType 字段类型

类型	值类型	说明
Text	String	文本，普通单行文本组件。
*MultiText	String	多行文本，富文本组件。
Number	Number	数字类型组件。
*Amount	Number	金额类组件。
Date	Date	日期，以 "年-月-日" 形式展示的日期组件
*DateTime	Date	日期 + 时间，以 "年-月-日 时:分" 形式展示的日期组件
*DateTimeSecond	Date	日期 + 时间（秒），以 "年-月-日 时:分:秒" 形式展示的日期组件
Checkbox	Boolean	布尔，以勾选框形式展示的组件
*Select	Object	下拉选择组件，选项需要通过 addSelectOption 来提供。
EntityRef	Object	档案、单据引用，以参照为展现形式的组件
EnumRef	Object	枚举引用，以枚举为展现形式的组件

Tabs 页签容器

Tabs 是页签容器的API对象。你可以通过 Tabs 添加页签Tab。Tabs的页签展示顺序保持和 addFieldSetTab 、addSubGridTab 的调用顺序一致。

类型	名称	参数类型	返回类型/类型	说明
方法	addFieldSetTab(options)	AddFieldSetTabOptions	FieldSet	添加一个字段集合的子页签
方法	addSubGridTab(options)	AddSubGridTabOptions	SubGrid	添加一个明细表的子页签

注意

如果页签容器下没有通过 addFieldSetTab 或 addSubGridTab 来添加页签，那么最终这个页签容器不会进行渲染。

addFieldSetTab(options) 添加字段集合页签

addFieldSetTab 用于在页签容器中添加一个字段集合页签。

options 参数

名称	类型	说明	必填	默认值
title	string	字段标题	☑️	""
fieldsPerLine	number	每行显示字段个数		4

注意

addFieldSetTab 中，title 属性必填。

返回值

FieldSet 字段集合

语法

// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();

// 添加一个页签分组
const tabs = formDialogBuilder.addTabs();

// 在页签分组下添加一个标题为“销售属性”的页签
const salesTab = tabs.addFieldSetTab({
  title: "销售属性"
});

// 在“销售属性”页签中，添加“售价”字段
salesTab.addField({
  id: "price",
  title: "售价",
  type: "Amount"
});

addSubGridTab(options) 添加明细表页签

addSubGridTab 用于在页签容器中添加一个明细表页签。

options 参数

名称	类型	说明	必填	默认值
fieldName	string	明细表字段名	☑️	-
title	string	明细表标题	☑️	-

注意

addSubGridTab 中，title 属性必填。

返回值

SubGrid 明细表

语法

// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();

// 添加一个页签分组
const tabs = formDialogBuilder.addTabs();

// 在 “销售属性” 右侧，添加一个标题为“库存属性”的页签，这个页签里显示一个明细表
const inventoryGrid = tabs.addSubGridTab({
  title: "库存属性"
  fieldName: "inventories"
});

// 库存属性明细表中，添加一个标题为"存货"的列
inventoryGrid.addField({
  id: 'product',
  title: '存货',
  type: 'EntityRef',
  source: 'Product'
})

SubGrid 明细表

SubGrid 是明细表的API对象。你可以通过 SubGrid 给明细表定义其数据结构和前端渲染组件。

类型	名称	返回类型/类型	说明
方法	addField(options)	Field	在明细表中添加一个字段。

注意

如果 SubGrid 没有通过 addField 添加过字段，那么最终该明细表不会渲染，并且在表单中，也不会创建该明细表的数据模型对象。

addField(options) 添加字段

在明细表中添加一个字段。添加的多个字段会按照 addField 的调用顺序从左到右进行排列。

options 参数

名称	类型	说明	必填	默认值
id	string	字段名称	☑️	-
title	string	字段标题	☑️	-
type	FieldType	字段类型	☑️	-
source	string	当 type = "EntityRef" 或 "EnumRef" 时， 通过 source 指定引用对象。		-

返回值

Field 字段

语法

// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();

// 添加一个标题为“人员明细”的明细表区域
const userGrid = formDialogBuilder.addSubGrid({
  fieldName: 'users',
  title: "人员明细"
});

// 在明细表中，添加一个标题为“人员”的外键字段，外键指向 User 表，并设置列宽为 200.
const user = userGrid.addField({
  id: "user",
  title: "人员",
  type: "EntityRef",
  source: "User"
  width: 200
});

// 在明细表中，添加一个标题为“天数”的数字字段，该字段会显示在“人员”右侧。
userGrid.addField({
  id: "days",
  title: "天数",
  type: "Number"
});